What happens if there is an error? Do we rollback automatically? Does the user have to do this manually?

Nope, and I'll add a to do item to make sure we rollback if the commit call fails. So, how does this case work:

transaction.commit(function(err) {
  // Behind the scenes, we see that this call fails.
  // So before executing this callback, we should automatically rollback.

  // What happens if the user didn't catch that part in the docs, and tries
  // to rollback themselves?
  if (err) {
    transaction.rollback(...);
  }
});

We just need to make sure to swallow any errors on the automatic rollback -- it will get an error:

INVALID_ARGUMENT: The referenced transaction has expired or is no longer valid.

/cc @jdimond

Added a commit to automatically rollback after a failed commit: 41eec47

To verify -- if an error happens during the BeginTransaction call, all attempted calls as part of that transaction will fail, correct?

Are we worried users may try to do something like:

datastore.transaction().run(....) and then use datastore instead of transaction inside that run method?

if an error happens during the BeginTransaction call, all attempted calls as part of that transaction will fail, correct?

var transaction = datastore.transaction();

transaction.run(function(err) {
  if (err) {
    // BeginTransaction failed
  }
});

Calling anything else from transaction will return whatever error the API will.

Are we worried users may try to do something like: datastore.transaction().run(....) and then use datastore instead of transaction inside that run method?

That's a fair concern. We could return the transaction as the second argument to the run callback:

transaction.run(function(err, tx) { /* transaction === tx */ });
datastore.transaction().run(function(err, transaction) {});

Just to be sure -- there are cases where someone might want to start a transaction, and then from outside the transaction execute a query of sorts, right?

If there is no good reason to ever do:

transaction.run( (err) => {
  datastore.run(somethingElse);
  transaction.commit();
});

then we should throw an error if people try to do something like that.... ?

I think I'm a bit confused by your example. run is only a method on a Transaction object, so
datastore.run(somethingElse); would throw.

Sorry - I mean it as an example of "running another query from inside that block". Is there a time when that would make sense? That'd I'd get an entity while inside a transaction block, but not want to use the transaction ?

Gotcha. In terms of a use case, I'm not sure.

I don't think I'd block those operations, though. I'm not sure how, actually... choosing where a function can be executed or not:

transaction.run(function (err) {
  datastore.get(key, function(err, entity) {})
  //        ^-- need to detect this was executed inside of `transaction.run`
})

If this is what we want, maybe @callmehiphop and I can think of something clever. However, I think the user would expect if they have something that works in one place, it would work wherever they choose to put it.

@callmehiphop PTAL

Coverage remained the same at 100.0% when pulling 3f8c632 on stephenplusplus:spp--633 into 50d465b on GoogleCloudPlatform:master.

Coverage remained the same at 100.0% when pulling 5aa2c44 on stephenplusplus:spp--633 into 50d465b on GoogleCloudPlatform:master.